COMMENT ⊗   VALID 00002 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	%Start Part 6 of 8 functi.tex
C00025 ENDMK
C⊗;
%Start Part 6 of 8 functi.tex
The function {\bf invalid-method-error} is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
{\bf define-method-combination} form.  A method combination function
that imposes additional restrictions should call {\bf
invalid-method-error} explicitly if it encounters a method it cannot
accept.

\label Syntax:

\Defun {invalid-method-error} {method format-string {\rest} args}

\label Arguments:

The {\it method\/} argument is the invalid method object.  

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

Whether {\bf invalid-method-error} returns to its caller or exits via
{\bf throw} is implementation dependent.

\label See Also: 

{\bf define-method-combination}

\endcom


\begincom{make-instance}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf make-instance} creates and returns a new
instance of the given class.

The generic function {\bf make-instance} may be used as described in
the section ``Object Creation and Initialization.''

\label Syntax:

\Defgen {make-instance} {class\/ {\tt \&rest {\it initargs}}}

\label Method Signatures:

\Defmeth {make-instance} {({\it class\/} standard-class) \&rest {\it initargs}}

\Defmeth {make-instance} {({\it class\/} symbol) \&rest {\it initargs}}

\label Arguments:

The {\it class\/} argument is a class object or a symbol that
names a class.  The remaining arguments form a list of alternating
initialization argument names and values.

If the second of the above methods is selected, that method invokes
{\bf make-instance} on the arguments {\tt (find-class {\it class\/})} and
{\it initargs}.

The initialization arguments are checked within {\bf make-instance}.
See the section ``Object Creation and Initialization.''

\label Values:

The new instance is returned.

\label Remarks:

The meta-object protocol can be used to define new methods on {\bf
make-instance} to replace the object-creation protocol.

\label See Also:

``Object Creation and Initialization''

{\bf defclass

initialize-instance

class-of}

\endcom




\begincom{make-instances-obsolete}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf make-instances-obsolete} is invoked
automatically by the system when {\bf defclass} has been used to
redefine an existing standard class and the set of local slots accessible in an
instance is changed or the order of slots in storage is changed.  It
can also be explicitly invoked by the user.

The function {\bf make-instances-obsolete} has the effect of
initiating the process of updating the instances of the
class. During updating, the generic function {\bf
update-instance-for-redefined-class} will be invoked.

\label Syntax:

\Defgen {make-instances-obsolete} {class}

\label Method Signatures:

\Defmeth {make-instances-obsolete} {({\it class\/} standard-class)}

\Defmeth {make-instances-obsolete} {({\it class\/} symbol)}

\label Arguments:

The {\it class\/} argument is a class object or a symbol that names
the class whose instances are to be made obsolete.

If the second of the above methods is selected, that method invokes
{\bf make-instances-obsolete} on {\tt (find-class {\it class\/})}.

\label Values:

The modified class is returned.  The result of {\bf make-instances-obsolete}
is {\bf eq} to the {\it class} argument supplied to the first of the above
methods.

\label See Also:

``Redefining Classes''

{\bf update-instance-for-redefined-class}

\endcom




\begincom{method-combination-error}\ftype{Function}

\label Purpose:

The function {\bf method-combination-error} is used to signal an error
in method combination.  The error message is constructed by using a
format string and any arguments to it.  Because an implementation may
need to add additional contextual information to the error message,
{\bf method-combination-error} should be called only within the
dynamic extent of a method combination function.

\label Syntax:

\Defun {method-combination-error} {format-string {\rest} args}

\label Arguments: 

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

Whether {\bf method-combination-error} returns to its caller or exits
via {\bf throw} is implementation dependent.

\label See Also: 

{\bf define-method-combination}

\endcom




\begincom{method-qualifiers}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf method-qualifiers} returns a list of the
qualifiers of the given method.

\label Syntax:

\Defgen {method-qualifiers} {method}

\label Method Signatures:

\Defmeth {method-qualifiers} {({\it method\/} standard-method)}

\label Arguments:

The {\it method\/} argument is a method object. 

\label Values:

A list of the qualifiers of the given method is returned.

\label Examples:

\screen!

(setq methods (remove-duplicates methods
                                 :from-end t
                                 :key #'method-qualifiers
                                 :test #'equal))

\endscreen!

\label See Also: 

{\bf define-method-combination}

\endcom

 

\begincom{next-method-p}\ftype{Function}

\label Purpose:

The locally defined function {\bf next-method-p} can be used within
the body of a method defined by a method-defining form to determine
whether a next method exists.

\label Syntax:

\Defun {next-method-p} {}

\label Arguments:

The function {\bf next-method-p} takes no arguments.

\label Values:

The function {\bf next-method-p} returns true or false.

\label Remarks:

Like {\bf call-next-method}, the function {\bf next-method-p} has 
lexical scope and indefinite extent.

\label See Also:

{\bf call-next-method}

\endcom


\begincom{no-applicable-method}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf no-applicable-method} is called when a
generic function of the class {\bf standard-generic-function} is invoked
and no method on that generic function is applicable.
The default method signals an error.

The generic function {\bf no-applicable-method} is not intended to be called
by programmers.  Programmers may write methods for it.

\label Syntax:

\Defgen {no-applicable-method} {generic-function {\rest} function-arguments}

\label Method Signatures:

\Defmeth {no-applicable-method} {\vtop{\hbox{({\it generic-function\/} t)}
\hbox{\&rest {\it function-arguments\/}}}}

\label Arguments:

The {\it generic-function\/} argument of {\bf no-applicable-method} is the
generic function object on which no applicable method was found.  

The {\it function-arguments} argument is a list of the arguments to that
generic function.

\endcom

\begincom{no-next-method}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf no-next-method} is called by {\bf
call-next-method} when there is no next method.  The system-supplied
method on {\bf no-next-method} signals an error.

The generic function {\bf no-next-method} is not intended to be called
by programmers.  Programmers may write methods for it.

\label Syntax:

\Defgen {no-next-method} {generic-function method {\rest} args}

\label Method Signatures:

\Defmeth {no-next-method} {\vtop{\hbox{({\it generic-function\/} standard-generic-function)}
\hbox{({\it method\/} standard-method)}
\hbox{\&rest {\it args\/}}}}

\label Arguments:

The {\it generic-function\/} argument is the generic function object
to which the method that is the second argument belongs.

The {\it method\/} argument is the method that contained the call to
{\bf call-next-method} for which there is no next method.

The {\it args\/} argument is a list of the arguments to
{\bf call-next-method}.

\label See Also:

{\bf call-next-method}

\endcom


\begincom{print-object}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf print-object} writes the printed
representation of an object to a stream.  The function {\bf
print-object} is called by the print system; it should not be called
by the user.

Each implementation is required to provide a method on the class {\bf
standard-object} and methods on enough other classes so as to ensure
that there is always an applicable method.  Implementations are free
to add methods for other classes.  Users can write methods for {\bf
print-object} for their own classes if they do not wish to inherit an
implementation-supplied method.

\label Syntax:

\Defgen {print-object} {object stream}

\label Method Signatures:

\Defmeth {print-object} {({\it object\/} standard-object) {\it stream\/}}

\label Arguments:

The first argument is any Lisp object.   The second argument is a
stream; it cannot be {\bf t} or {\bf nil}. 

\label Values:

The function {\bf print-object} returns its first argument, the object.  

\label Remarks:

Methods on {\bf print-object} must obey the print control special
variables described in {\it Common Lisp: The Language}.  The
specific details are the following:

\beginlist

\item{\bull}
Each method must implement {\bf *print-escape*}. 

\item{\bull} 
The {\bf *print-pretty*} control variable can be ignored
by most methods other than the one for lists.

\item{\bull}
The {\bf *print-circle*} control variable is handled by the printer
and can be ignored by methods.

\item{\bull}
The printer takes care of {\bf *print-level*} automatically, provided that
each method handles exactly one level of structure and
calls {\bf write} (or an equivalent function) recursively if
there are more structural levels.  The printer's decision
of whether an object has components (and therefore should
not be printed when the printing depth is not less than
{\bf *print-level*}) is implementation dependent.  In some
implementations its {\bf print-object} method is not called; in
others the method is called, and the determination that the
object has components is based on what it tries to write
to the stream.

\item{\bull}
Methods that produce output of indefinite length must obey
{\bf *print-length*}, but most methods other than the one for lists can
ignore it.

\item{\bull}
The {\bf *print-base*}, {\bf *print-radix*}, {\bf *print-case*}, {\bf
*print-gensym*}, and {\bf *print-array*} control variables apply
to specific types of objects and are handled by the methods for those
objects.

\endlist

If these rules are not obeyed, the results are undefined.

In general, the printer and the {\bf print-object} methods should not
rebind the print control variables as they operate recursively through the
structure, but this is implementation dependent.

In some implementations the stream argument passed to a {\bf
print-object} method is not the original stream, but is an
intermediate stream that implements part of the printer.  Methods
should therefore not depend on the identity of this stream.

All of the existing printing functions ({\bf write}, {\bf prin1}, {\bf
print}, {\bf princ}, {\bf pprint}, {\bf write-to-string}, {\bf
prin1-to-string}, {\bf princ-to-string}, the {\tt ~}{\bf S} and {\tt
~}{\bf A} format operations, and the {\tt ~}{\bf B}, {\tt ~}{\bf D},
{\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf G}, {\tt ~}{\bf \$}, {\tt
~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf X} format operations when they
encounter a non-numeric value) are required to be changed to go
through the {\bf print-object} generic function.  Each implementation is
required to replace its former implementation of printing with one or
more {\bf print-object} methods.  Exactly which classes have methods for
{\bf print-object} is not specified; it would be valid for an implementation
to have one default method that is inherited by all system-defined
classes.

\endcom



\begincom{reinitialize-instance}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf reinitialize-instance} can be used to change
the values of local slots according to initialization arguments.  This
generic function is called by the Meta-Object Protocol.   It can also be
called by users.

The system-supplied primary method for {\bf reinitialize-instance}
checks the validity of initialization arguments and signals an error if
an initialization argument is supplied that is not declared as valid.
The method then calls the generic function {\bf shared-initialize}
with the following arguments:  the instance, {\bf nil} (which means no slots
should be initialized according to their initforms), and the
initialization arguments it received.

\label Syntax:

\Defgen {reinitialize-instance} {instance {\tt \&rest {\it initargs}}}

\label Method Signatures:

\Defmeth {reinitialize-instance} {({\it instance\/} standard-object) {\rest} {\it initargs}} 

\label Arguments:

The {\it instance\/} argument is the object to be initialized.

The {\it initargs\/} argument consists of alternating initialization
argument names and values.

\label Values:

The modified instance is returned as the result.

\label Remarks:

Initialization arguments are declared as valid by using the {\bf
:initarg} option to {\bf defclass}, or by defining methods for {\bf
reinitialize-instance} or {\bf shared-initialize}.  The keyword name
of each keyword parameter specifier in the lambda-list of any method
defined on {\bf reinitialize-instance} or {\bf shared-initialize} is
declared as a valid initialization argument name for all classes for
which that method is applicable.

\label See Also:

``Reinitializing an Instance''

``Rules for Initialization Arguments''

``Declaring the Validity of Initialization Arguments''

{\bf initialize-instance

shared-initialize

update-instance-for-redefined-class

update-instance-for-different-class

slot-boundp

slot-makunbound}

\endcom



\begincom{remove-method}\ftype{Standard Generic Function}

\label Purpose:

The generic function {\bf remove-method} removes a method from a
generic function.  It destructively modifies the specified generic
function and returns the modified generic function as its result.

%End Part 6 of 8 functi.tex